PicketLink AS7 Subsystem

Overview

The PicketLink AS7 Subsystem is an AS7 extension that provides an infrastructure to deploy and manage PicketLink applications using JBoss AS 7.

It defines a domain model that can be manipulated using a client interface like the Management Console or CLI interface and also makes easier to configure any application as an Identity Provider and Service Provider.

More information on the PicketLink AS7 Subsystem can be found on this thread.

New configuration model for PicketLink applications

By providing a domain model, all the configuration is external from applications where there is no need to add or change configuration files inside the application being deployed. The subsystem is responsible for during deployment time properly configure the applications being deployed, according with the configurations defined in the domain model:

- The configurations in picketlink.xml are automatically created. No need to have this file inside your deployment.

- The PicketLink Authenticators (Apache Tomcat Valves) for Identity Providers and Service Providers are automatically registered. No need to have a jboss-web.xml file inside your deployment.

- The PicketLink dependencies are automatically configured. No need to have a jboss-deployment-structure.xml inside your deployment defining the org.picketlink module as a dependency.

- The Security Domain is automatically configured using the configurations defined in the domain model. No need to have a jboss-web.xml file inside your deployment.

The table bellow sumarizes the main differences between the traditional configuration and the subsystem configuration for PicketLink applications:

Configuration	Traditional Config	Subsystem Config
WEB-INF/picketlink.xml	Required	Not required. If present it will be considered instead of the configurations defined in the domain model.
WEB-INF/jboss-web.xml	Required	Not required. The PicketLink Authenticators (Tomcat Valves) and the Security Domain is read from the domain model.
META-INF/jboss-deployment-structure.xml	Required	Not required. When the PicketLink Extension/Subsystem is enabled, the dependency to the org.picketlink module is automatically configured.

The Federation concept (Circle of Trust)

When using the PicketLink subsystem to configure and deploy your identity providers and service providers, all of them are grouped in a Federation.

A Federation can be understood as a Circle of Trust (CoT) from which applications share common configurations (certificates, saml specific configurations, etc) and where each participating domain is trusted to accurately document the processes used to identify a user, the type of authentication system used, and any policies associated with the resulting authentication credentials.

Each federation has one Identity Provider and many Service Providers. You do not need to specify for each SP the IDP that it trusts, because this is defined by the federation.

Management capabilities

One of the benefits about using the PicketLink subsystem to deploy your applications is that they can be managed in different ways:

PicketLink Console
The console provides a UI, based on the AS7 Administration Console, to help manage your PicketLink deployments. Basically, all the configuration defined in the domain model can be managed using the console.

JBoss AS7 CLI Interface (Native Interface)
The CLI interface provides a command line tool from where you can query and change all the configuration defined for your applications.

JBoss AS7 HTTP Interface
JBoss AS7 allows you to manage your running installations using the HTTP protocol with a JSON encoded protocol and a de-typed RPC style API.

Metrics and Statistics

Metrics and statistics can be collected from applications deployed using the PicketLink subsystem. This means you can get some useful information about how your Identity Providers and Service providers are working.

How many SAML assertions were issued by your identity provider ?
How many times your identity provider respond to service providers ?
How many SAML assertions were expired ?
How many authentications are done by your identity provider ?
How many errors happened ? Trusted Domain errors, signing errors, etc.

PicketLink Domain Model

The PicketLink Domain Model is an abstraction for all PicketLink configuration, providing a single schema from which all configurations can be defined for Identity Providers or Service Providers, for example.

The example bellow shows how the domain model can used to configure an Identity Provider and a Service Provider.

<subsystem xmlns="urn:jboss:picketlink:1.0">

    <federation alias="federation-without-signatures">

        <saml token-timeout="4000" clock-skew="0" />

        <identity-provider alias="idp.war" security-domain="idp" supportsSignatures="false" url="http://localhost:8080/idp/">
            <trust>
                <trust-domain name="localhost" />
                <trust-domain name="mycompany.com2" />
                <trust-domain name="mycompany.com3" />
                <trust-domain name="mycompany.com4" />
            </trust>
            <handlers>
                <handler class="com.mycompany.CustomHandler">
                    <handler-parameter name="param1" value="paramValue1"/>
                    <handler-parameter name="param2" value="paramValue2"/>
                    <handler-parameter name="param3" value="paramValue3"/>
                </handler>
            </handlers>
        </identity-provider>

        <service-providers>
            <service-provider alias="sales.war" post-binding="true" security-domain="sp" url="http://localhost:8080/sales/" supportsSignatures="false">
                <handlers>
                    <handler class="com.mycompany.CustomHandler">
                        <handler-parameter name="param1" value="paramValue1"/>
                        <handler-parameter name="param2" value="paramValue2"/>
                        <handler-parameter name="param3" value="paramValue3"/>
                    </handler>
                </handlers>
            </service-provider>
            <service-provider alias="employee.war" post-binding="true" security-domain="sp" url="http://localhost:8080/employee/" supportsSignatures="false" />
        </service-providers>
    </federation>

</subsystem>

If you are looking for more examples about how to use the domain model, take a look at https://github.com/picketlink/picketlink-as-subsystem/blob/master/src/test/resources/picketlink-subsystem.xml.

About the schema

If you are familiar with the PicketLink configuration you will find out that the domain model schema is just an abstraction to make the configuration even easier.

Schema location

The configuration schema can be found here.

Installation

requisites

Download JBoss Application Server 7.1.1.Final+.
Download PicketLink Subsystem libraries.
Download PicketLink 2.1.2.Final+.

First, download and install a JBoss AS 7 distribution.

Update your JBoss AS7 distribution with the latest PicketLink libraries. Follow the instructions in our JBoss Modules section.

Update the PicketLink Module definition

Copy the PicketLink Subsystem library to [jboss.server.home.dir]/modules/org/picketlink/main.

Change the module definition ([jboss.server.home.dir]/modules/org/picketlink/main/module.xml) with the contents bellow:

<?xml version="1.0" encoding="UTF-8"?>
<module xmlns="urn:jboss:module:1.1" name="org.picketlink"> 
    <resources> 
        <resource-root path="picketlink-jbas7-2.1.2.Final.jar" /> 
        <resource-root path="picketlink-core-2.1.2.Final.jar" /> 
        <resource-root path="jboss-as-security-picketlink-1.1.0.Final.jar" /> 
    </resources> 
    <dependencies> 
        <module name="javax.annotation.api" /> 
        <module name="org.jboss.staxmapper" /> 
        <module name="org.jboss.as.controller" /> 
        <module name="org.jboss.as.server" /> 
        <module name="org.jboss.modules" /> 
        <module name="org.jboss.msc" /> 
        <module name="org.jboss.logging" /> 
        <module name="org.jboss.vfs" /> 
        <module name="org.jboss.metadata"/> 
        <module name="org.jboss.as.naming"/> 
        <module name="org.jboss.as.security"/> 
        <module name="org.jboss.as.webservices"/> 
        <module name="org.jboss.ws.spi"/> 
        <module name="org.apache.cxf"/> 
        <module name="org.apache.ws.security"/> 
        <module name="javax.wsdl4j.api"/> 
        <module name="javax.security.auth.message.api" /> 
        <module name="javax.security.jacc.api" /> 
        <module name="javax.transaction.api" /> 
        <module name="javax.xml.bind.api" /> 
        <module name="javax.xml.stream.api" /> 
        <module name="javax.servlet.api" /> 
        <module name="org.jboss.common-core" /> 
        <module name="org.jboss.logging" /> 
        <module name="org.jboss.as.web" /> 
        <module name="org.jboss.security.xacml" /> 
        <module name="org.picketbox" /> 
        <module name="javax.xml.ws.api" /> 
        <module name="org.apache.log4j" /> 
        <module name="org.apache.santuario.xmlsec" /> 
        <module name="javax.api" /> 
    </dependencies>
</module>

Make sure the resources section is pointing to the correct libraries and their file names.

Configure the PicketLink Extension

Change your standalone.xml to add the PicketLink Extension:

<extensions>
    ...
    <extension module="org.picketlink"/>
</extensions>

How to Use

Configure the example applications

Take a look at the documentation for the PicketLink Quickstarts.

Download the example web applications.

Extract the file and copy the idp.war and sales.war to [jboss.home.dir]/standalone/deployments.

Open both files (idp.war and sales.war) and remove the following configuration files:

WEB-INF/picketlink.xml
META-INF/jboss-deployment-structure.xml
WEB-INF/jboss-web.xml

Don't forget to configure the security domains for both applications. Check the PicketLink Quickstarts documentation for more information.

Define the PicketLink subsystem configuration

Open the standalone.xml and add the following configuration for the PicketLink subsystem:

<subsystem xmlns="urn:jboss:picketlink:1.0">

    <federation alias="example-federation">
        <identity-provider alias="idp.war" security-domain="idp" supportsSignatures="false" url="http://localhost:8080/idp/">
            <trust>
                <trust-domain name="localhost" />
            </trust>
        </identity-provider>

        <service-providers>
            <service-provider alias="sales.war" post-binding="false" security-domain="sp" url="http://localhost:8080/sales/" supportsSignatures="false" />
        </service-providers>
    </federation>

</subsystem>

To make sure that everything is ok, please start the JBoss AS and try to access the sales application. You should be redirected to the idp application. If you want to login at the sales and idp applications, don't forget to configure the security domain for both.

Using the CLI command line tool

As said before, you can use the CLI command line tool to query the PicketLink subsystem configuration.

Execute the [jboss.server.home.dir]/bin/jboss-cli.sh script and connect to your running JBoss Application Server instance.

[user@palatino bin]$ ./jboss-cli.sh
You are disconnected at the moment. Type 'connect' to connect to the server or 'help' for the list of supported commands.
[disconnected /] connect
[standalone@localhost:9999 /]

Now that you are connected query the federation resource to see its child resources:

[standalone@localhost:9999 federation=example-federation]cd /subsystem=picketlink/federation=example-federation
[standalone@localhost:9999 federation=example-federation]ls
identity-provider          key-store                  saml                       service-provider           alias=example-federation

Let's now read the identity provider resource:

[standalone@localhost:9999 federation=example-federation] ./identity-provider=idp.war:read-resource
{
    "outcome" => "success",
    "result" => {
        "alias" => "idp.war",
        "external" => false,
        "handler" => undefined,
        "security-domain" => "idp",
        "strict-post-binding" => false,
        "supportsSignatures" => false,
        "url" => "http://localhost:8080/idp",
        "trust-domain" => {"localhost" => undefined}
    }
}

You can also use the read-resource(include-runtime=true) operation to query some metrics:

[standalone@localhost:9999 federation=example-federation] ./identity-provider=idp.war:read-resource(include-runtime=true)
{
    "outcome" => "success",
    "result" => {
         "alias" => "idp.war",
         "created-assertions-count" => "1",
         "error-response-to-sp-count" => "0",
         "error-sign-validation-count" => "0",
         "error-trusted-domain-count" => "0",
         "expired-assertions-count" => "0",
         "external" => false,
         "handler" => undefined,
         "login-complete-count" => "0",
         "login-init-count" => "0",
         "response-to-sp-count" => "3",
         "security-domain" => "idp",
         "strict-post-binding" => false,
         "supportsSignatures" => false,
         "url" => "http://localhost:8080/idp",
         "trust-domain" =>{"localhost" => undefined}
    }
}

Deploying applications using the traditional configuration

You can always use the traditional configuration (with all files inside your deployment) if you want to. To do that, you can:

1) Remove the PicketLink subsystem configuration from the JBoss AS7 configuration (standalone.xml) and add to your deployments the missing files: WEB-INF/picketlink.xml, WEB-INF/jboss-web.xml and META-INF/jboss-deployment-structure.xml.

2) Use the PicketLink subsystem configuration to automatically configure the dependencies and security domain, but consider the configurations defined in the WEB-INF/picketlink.xml file inside your deployment instead of the subsystem configuration for IDPs or SPs.

When using the subsystem, is recommended that you use only the domain model configuration to your IDPs and SPs. It is easier to configure and less intrusive than the traditional approach.